IRIX Base Documentation 2001 May/SGI IRIX Base Documentation 2001 May.iso/usr/share/catman/p_man/cat3c/directory.z/directory

Text File | 1998-10-20 | 18.8 KB | 265 lines

ddddiiiirrrreeeeccccttttoooorrrryyyy((((3333CCCC))))                                                    ddddiiiirrrreeeeccccttttoooorrrryyyy((((3333CCCC))))



NNNNAAAAMMMMEEEE
     _dddd_iiii_rrrr_eeee_cccc_tttt_oooo_rrrr_yyyy: _oooo_pppp_eeee_nnnn_dddd_iiii_rrrr, _rrrr_eeee_aaaa_dddd_dddd_iiii_rrrr, _rrrr_eeee_aaaa_dddd_dddd_iiii_rrrr_6666_4444, _tttt_eeee_llll_llll_dddd_iiii_rrrr, _tttt_eeee_llll_llll_dddd_iiii_rrrr_6666_4444, _ssss_eeee_eeee_kkkk_dddd_iiii_rrrr,
     _ssss_eeee_eeee_kkkk_dddd_iiii_rrrr_6666_4444, _rrrr_eeee_wwww_iiii_nnnn_dddd_dddd_iiii_rrrr, _cccc_llll_oooo_ssss_eeee_dddd_iiii_rrrr, _rrrr_eeee_aaaa_dddd_dddd_iiii_rrrr______rrrr, _rrrr_eeee_aaaa_dddd_dddd_iiii_rrrr_6666_4444______rrrr - directory
     operations

SSSSYYYYNNNNOOOOPPPPSSSSIIIISSSS
     _####_iiii_nnnn_cccc_llll_uuuu_dddd_eeee _<<<<_dddd_iiii_rrrr_eeee_nnnn_tttt_...._hhhh_>>>>

     _DDDD_IIII_RRRR _****_oooo_pppp_eeee_nnnn_dddd_iiii_rrrr _((((_cccc_oooo_nnnn_ssss_tttt _cccc_hhhh_aaaa_rrrr _****_ffff_iiii_llll_eeee_nnnn_aaaa_mmmm_eeee_))))_;;;;

     _ssss_tttt_rrrr_uuuu_cccc_tttt _dddd_iiii_rrrr_eeee_nnnn_tttt _****_rrrr_eeee_aaaa_dddd_dddd_iiii_rrrr _((((_DDDD_IIII_RRRR _****_dddd_iiii_rrrr_pppp_))))_;;;;

     _ssss_tttt_rrrr_uuuu_cccc_tttt _dddd_iiii_rrrr_eeee_nnnn_tttt_6666_4444 _****_rrrr_eeee_aaaa_dddd_dddd_iiii_rrrr_6666_4444 _((((_DDDD_IIII_RRRR _****_dddd_iiii_rrrr_pppp_))))_;;;;

     _oooo_ffff_ffff______tttt _tttt_eeee_llll_llll_dddd_iiii_rrrr _((((_DDDD_IIII_RRRR _****_dddd_iiii_rrrr_pppp_))))_;;;;

     _oooo_ffff_ffff_6666_4444______tttt _tttt_eeee_llll_llll_dddd_iiii_rrrr_6666_4444 _((((_DDDD_IIII_RRRR _****_dddd_iiii_rrrr_pppp_))))_;;;;

     _vvvv_oooo_iiii_dddd _ssss_eeee_eeee_kkkk_dddd_iiii_rrrr _((((_DDDD_IIII_RRRR _****_dddd_iiii_rrrr_pppp_,,,, _oooo_ffff_ffff______tttt _llll_oooo_cccc_))))_;;;;

     _vvvv_oooo_iiii_dddd _ssss_eeee_eeee_kkkk_dddd_iiii_rrrr_6666_4444 _((((_DDDD_IIII_RRRR _****_dddd_iiii_rrrr_pppp_,,,, _oooo_ffff_ffff_6666_4444______tttt _llll_oooo_cccc_))))_;;;;

     _vvvv_oooo_iiii_dddd _rrrr_eeee_wwww_iiii_nnnn_dddd_dddd_iiii_rrrr _((((_DDDD_IIII_RRRR _****_dddd_iiii_rrrr_pppp_))))_;;;;

     _iiii_nnnn_tttt _cccc_llll_oooo_ssss_eeee_dddd_iiii_rrrr _((((_DDDD_IIII_RRRR _****_dddd_iiii_rrrr_pppp_))))_;;;;

     _iiii_nnnn_tttt _rrrr_eeee_aaaa_dddd_dddd_iiii_rrrr______rrrr _((((_DDDD_IIII_RRRR _****_dddd_iiii_rrrr_pppp_,,,, _ssss_tttt_rrrr_uuuu_cccc_tttt _dddd_iiii_rrrr_eeee_nnnn_tttt _****_eeee_nnnn_tttt_rrrr_yyyy_,,,, _ssss_tttt_rrrr_uuuu_cccc_tttt _dddd_iiii_rrrr_eeee_nnnn_tttt _****_****_rrrr_eeee_ssss_))))_;;;;

     _iiii_nnnn_tttt _rrrr_eeee_aaaa_dddd_dddd_iiii_rrrr_6666_4444______rrrr _((((_DDDD_IIII_RRRR _****_dddd_iiii_rrrr_pppp_,,,, _ssss_tttt_rrrr_uuuu_cccc_tttt _dddd_iiii_rrrr_eeee_nnnn_tttt_6666_4444 _****_eeee_nnnn_tttt_rrrr_yyyy_,,,, _ssss_tttt_rrrr_uuuu_cccc_tttt _dddd_iiii_rrrr_eeee_nnnn_tttt_6666_4444
     _****_****_rrrr_eeee_ssss_))))_;;;;

DDDDEEEESSSSCCCCRRRRIIIIPPPPTTTTIIIIOOOONNNN
     The inclusion of <_d_i_r_e_n_t._h> selects the System V versions of these
     routines.  For the 4.3BSD versions, include <_s_y_s/_d_i_r._h>.  The 64-bit
     interfaces are not present in the 4.3BSD versions.

     _o_p_e_n_d_i_r opens the directory named by _f_i_l_e_n_a_m_e and associates a directory
     stream with it.  _oooo_pppp_eeee_nnnn_dddd_iiii_rrrr returns a pointer to be used to identify the
     directory stream in subsequent operations.  The directory stream is
     positioned at the first entry.  A null pointer is returned if _f_i_l_e_n_a_m_e
     cannot be accessed or is not a directory, or if it cannot _mmmm_aaaa_llll_llll_oooo_cccc(3C)
     enough memory to hold a _DDDD_IIII_RRRR structure or a buffer for the directory
     entries.

     _rrrr_eeee_aaaa_dddd_dddd_iiii_rrrr returns a pointer to the next active directory entry and
     positions the directory stream at the next entry.  No inactive entries
     are returned.  It returns _NNNN_UUUU_LLLL_LLLL upon reaching the end of the directory or
     upon detecting an invalid location in the directory.  _rrrr_eeee_aaaa_dddd_dddd_iiii_rrrr buffers
     several directory entries per actual read operation; _rrrr_eeee_aaaa_dddd_dddd_iiii_rrrr marks for
     update the _ssss_tttt______aaaa_tttt_iiii_mmmm_eeee field of the directory each time the directory is
     actually read.




                                                                        PPPPaaaaggggeeee 1111






ddddiiiirrrreeeeccccttttoooorrrryyyy((((3333CCCC))))                                                    ddddiiiirrrreeeeccccttttoooorrrryyyy((((3333CCCC))))



     _rrrr_eeee_aaaa_dddd_dddd_iiii_rrrr______rrrr is a reentrant version of _rrrr_eeee_aaaa_dddd_dddd_iiii_rrrr.  The directory entry at the
     current position in _dddd_iiii_rrrr_pppp is copied into _e_n_t_r_y.  The storage pointed to by
     _e_n_t_r_y shall be large enough for a _d_i_r_e_n_t with an array of _c_h_a_r _d__n_a_m_e
     member containing at least {_N_A_M_E__M_A_X} plus one elements.  Upon successful
     return, the pointer returned at *_r_e_s_u_l_t shall have the same value as the
     argument _e_n_t_r_y.  Upon reaching the end of the directory stream, this
     pointer shall have the value _NNNN_UUUU_LLLL_LLLL.

     _tttt_eeee_llll_llll_dddd_iiii_rrrr returns the current location associated with the named directory
     stream.

     _ssss_eeee_eeee_kkkk_dddd_iiii_rrrr sets the position of the next _rrrr_eeee_aaaa_dddd_dddd_iiii_rrrr operation on the directory
     stream.  The new position reverts to the position associated with the
     directory stream at the time the _tttt_eeee_llll_llll_dddd_iiii_rrrr operation that provides _l_o_c was
     performed.  Values returned by _tttt_eeee_llll_llll_dddd_iiii_rrrr are valid only if the directory
     has not changed because of compaction or expansion.  This situation is
     not a problem with System V, but it may be a problem with some file
     system types.

     _rrrr_eeee_wwww_iiii_nnnn_dddd_dddd_iiii_rrrr resets the position of the named directory stream to the
     beginning of the directory.  It also causes the directory stream to refer
     to the current state of the corresponding directory, as a call to _oooo_pppp_eeee_nnnn_dddd_iiii_rrrr
     would.

     _cccc_llll_oooo_ssss_eeee_dddd_iiii_rrrr closes the named directory stream and frees the _DDDD_IIII_RRRR structure.

     _rrrr_eeee_aaaa_dddd_dddd_iiii_rrrr_6666_4444, _rrrr_eeee_aaaa_dddd_dddd_iiii_rrrr_6666_4444______rrrr, _ssss_eeee_eeee_kkkk_dddd_iiii_rrrr_6666_4444, and _tttt_eeee_llll_llll_dddd_iiii_rrrr_6666_4444 are parallel interfaces
     provided for cases where the information returned will not fit in the
     fields in the _dddd_iiii_rrrr_eeee_nnnn_tttt structure.  The fields in question are the inode
     number (_d__i_n_o) and the current offset (_d__o_f_f).  If it is necessary to
     call the 64-bit interfaces, and they are not called, an _EEEE_OOOO_VVVV_EEEE_RRRR_FFFF_LLLL_OOOO_WWWW error
     will result.  The 64-bit _rrrr_eeee_aaaa_dddd_dddd_iiii_rrrr and _tttt_eeee_llll_llll_dddd_iiii_rrrr interfaces should not be
     mixed with the non-64-bit interfaces in a sequence of calls.

     The following errors can occur as a result of these operations.

     _oooo_pppp_eeee_nnnn_dddd_iiii_rrrr returns _NNNN_UUUU_LLLL_LLLL on failure and sets _eeee_rrrr_rrrr_nnnn_oooo to one of the following
     values:

     _EEEE_NNNN_OOOO_TTTT_DDDD_IIII_RRRR             A component of _f_i_l_e_n_a_m_e is not a directory.

     _EEEE_AAAA_CCCC_CCCC_EEEE_SSSS              A component of _f_i_l_e_n_a_m_e denies search permission.

     _EEEE_AAAA_CCCC_CCCC_EEEE_SSSS              Read permission is denied on the specified directory.

     _EEEE_MMMM_FFFF_IIII_LLLL_EEEE              The maximum number of file descriptors are currently
                         open.

     _EEEE_NNNN_FFFF_IIII_LLLL_EEEE              The system file table is full.






                                                                        PPPPaaaaggggeeee 2222






ddddiiiirrrreeeeccccttttoooorrrryyyy((((3333CCCC))))                                                    ddddiiiirrrreeeeccccttttoooorrrryyyy((((3333CCCC))))



     _EEEE_FFFF_AAAA_UUUU_LLLL_TTTT              _f_i_l_e_n_a_m_e points outside the allocated address space.

     _EEEE_LLLL_OOOO_OOOO_PPPP               Too many symbolic links were encountered in
                         translating _f_i_l_e_n_a_m_e.

     _EEEE_NNNN_AAAA_MMMM_EEEE_TTTT_OOOO_OOOO_LLLL_OOOO_NNNN_GGGG        The length of the _f_i_l_e_n_a_m_e argument exceeds
                         _{{{{_PPPP_AAAA_TTTT_HHHH______MMMM_AAAA_XXXX_}}}}, or the length of a _f_i_l_e_n_a_m_e component
                         exceeds _{{{{_NNNN_AAAA_MMMM_EEEE______MMMM_AAAA_XXXX_}}}} while _{{{{______PPPP_OOOO_SSSS_IIII_XXXX______NNNN_OOOO______TTTT_RRRR_UUUU_NNNN_CCCC_}}}} is in
                         effect.

     _EEEE_NNNN_OOOO_EEEE_NNNN_TTTT              A component of _f_i_l_e_n_a_m_e does not exist or is a null
                         pathname.

     _rrrr_eeee_aaaa_dddd_dddd_iiii_rrrr returns _NNNN_UUUU_LLLL_LLLL on failure and sets _eeee_rrrr_rrrr_nnnn_oooo to one of the following
     values:

     _EEEE_NNNN_OOOO_EEEE_NNNN_TTTT              The current file pointer for the directory is not
                         located at a valid entry.

     _EEEE_BBBB_AAAA_DDDD_FFFF               The file descriptor determined by the _DDDD_IIII_RRRR stream is
                         no longer valid.  This result occurs if the _DDDD_IIII_RRRR
                         stream has been closed.

     _EEEE_DDDD_IIII_RRRR_CCCC_OOOO_RRRR_RRRR_UUUU_PPPP_TTTT_EEEE_DDDD       The directory is corrupted on disk.

     _EEEE_OOOO_VVVV_EEEE_RRRR_FFFF_LLLL_OOOO_WWWW           One of the inode number values or offset values did
                         not fit in 32 bits, and the 64-bit interfaces were
                         not used.

     _EEEE_IIII_NNNN_VVVV_AAAA_LLLL              64-bit and non-64-bit calls were mixed in a sequence
                         of calls.

     _rrrr_eeee_aaaa_dddd_dddd_iiii_rrrr______rrrr returns 0 on success and an error value (see above values for
     _rrrr_eeee_aaaa_dddd_dddd_iiii_rrrr) on error.

     _tttt_eeee_llll_llll_dddd_iiii_rrrr, _ssss_eeee_eeee_kkkk_dddd_iiii_rrrr, and  _cccc_llll_oooo_ssss_eeee_dddd_iiii_rrrr return -1 on failure and set _eeee_rrrr_rrrr_nnnn_oooo to the
     following value:

     _EEEE_BBBB_AAAA_DDDD_FFFF               The file descriptor determined by the _DDDD_IIII_RRRR stream is
                         no longer valid.  This results if the _DDDD_IIII_RRRR stream has
                         been closed.

     _EEEE_IIII_NNNN_VVVV_AAAA_LLLL              64-bit and non-64-bit calls were mixed in a sequence
                         of calls.

EEEEXXXXAAAAMMMMPPPPLLLLEEEE
     Here is a sample program that prints the names of all the files in the
     current directory:

          _####_iiii_nnnn_cccc_llll_uuuu_dddd_eeee _<<<<_ssss_tttt_dddd_iiii_oooo_...._hhhh_>>>>
          _####_iiii_nnnn_cccc_llll_uuuu_dddd_eeee _<<<<_dddd_iiii_rrrr_eeee_nnnn_tttt_...._hhhh_>>>>




                                                                        PPPPaaaaggggeeee 3333






ddddiiiirrrreeeeccccttttoooorrrryyyy((((3333CCCC))))                                                    ddddiiiirrrreeeeccccttttoooorrrryyyy((((3333CCCC))))



          _mmmm_aaaa_iiii_nnnn_((((_))))
          _{{{{
               _DDDD_IIII_RRRR _****_dddd_iiii_rrrr_pppp_;;;;
               _ssss_tttt_rrrr_uuuu_cccc_tttt _dddd_iiii_rrrr_eeee_nnnn_tttt _****_dddd_iiii_rrrr_eeee_nnnn_tttt_pppp_;;;;

               _dddd_iiii_rrrr_pppp _==== _oooo_pppp_eeee_nnnn_dddd_iiii_rrrr_(((( _""""_...._"""" _))))_;;;;
               _wwww_hhhh_iiii_llll_eeee _(((( _((((_dddd_iiii_rrrr_eeee_nnnn_tttt_pppp _==== _rrrr_eeee_aaaa_dddd_dddd_iiii_rrrr_(((( _dddd_iiii_rrrr_pppp _))))_)))) _!!!!_==== _NNNN_UUUU_LLLL_LLLL _))))
                    _((((_vvvv_oooo_iiii_dddd_))))_pppp_rrrr_iiii_nnnn_tttt_ffff_(((( _""""_%%%%_ssss_\\\\_nnnn_""""_,,,, _dddd_iiii_rrrr_eeee_nnnn_tttt_pppp_----_>>>>_dddd______nnnn_aaaa_mmmm_eeee _))))_;;;;
               _cccc_llll_oooo_ssss_eeee_dddd_iiii_rrrr_(((( _dddd_iiii_rrrr_pppp _))))_;;;;
               _rrrr_eeee_tttt_uuuu_rrrr_nnnn _((((_0000_))))_;;;;
          _}}}}

SSSSEEEEEEEE AAAALLLLSSSSOOOO
     _gggg_eeee_tttt_dddd_eeee_nnnn_tttt_ssss(2), _mmmm_kkkk_dddd_iiii_rrrr(2), _rrrr_mmmm_dddd_iiii_rrrr(2), _mmmm_aaaa_llll_llll_oooo_cccc(3C), _ssss_cccc_aaaa_nnnn_dddd_iiii_rrrr(3C), _dddd_iiii_rrrr_eeee_nnnn_tttt(4),
     _dddd_iiii_rrrr_eeee_cccc_tttt_oooo_rrrr_yyyy______bbbb_ssss_dddd(3B).

NNNNOOOOTTTTEEEESSSS
     These functions overwrite the buffer as needed, so applications should
     copy data to preserve it.

     The _tttt_eeee_llll_llll_dddd_iiii_rrrr_((((_)))) and _ssss_eeee_eeee_kkkk_dddd_iiii_rrrr_((((_)))) functions used long in place of off_t prior
     to IRIX 6.2.  This change makes no difference in the o32 and 64 bit
     compilation environments, but in the n32 compilation environment source
     that used to use a long may need to be changed to use an off_t instead.

BBBBUUUUGGGGSSSS
     The prototypes for _tttt_eeee_llll_llll_dddd_iiii_rrrr_((((_)))) and _ssss_eeee_eeee_kkkk_dddd_iiii_rrrr_((((_)))) in dirent.h use long rather
     than off_t in the o32 and 64 bit compilation environments.  This is
     harmless, however, because long and off_t are identical in these
     environments.

























                                                                        PPPPaaaaggggeeee 4444